home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / mxlibs / dwstk102 / dws.h < prev    next >
C/C++ Source or Header  |  1995-04-12  |  11KB  |  344 lines
  1. /******************************************************************************
  2. File:          dws.h
  3. Version:     1.02
  4. Tab stops: every 2 columns
  5. Project:     The Sound ToolKit
  6. Copyright: 1994-1995 DiamondWare, Ltd.    All rights reserved.
  7. Written:     by Keith Weiner and Erik Lorenzen
  8. Purpose:     Contains declarations for the DW Sound ToolKit
  9. History:     94/08/24 KW Started
  10.                      95/02/17 EL Finalized for v1.0
  11.                      95/03/19 EL Finalized for v1.01, Added new define dws_BUSY
  12.                      95/04/06 EL Finalized for v1.02, Added new define dws_IRQDISABLED
  13. ******************************************************************************/
  14.  
  15.  
  16.  
  17. #ifndef dws_INCLUDE
  18.  
  19.     #define dws_INCLUDE
  20.  
  21.  
  22.  
  23. /*****************************************************************************/
  24.     /*
  25.      . The following is the complete list of possible values for dws_ErrNo.
  26.      . dws_ErrNo may be set by any dws_ function.  Check its value whenever
  27.      . the return value of a dws_ function is 0 (error).
  28.     */
  29.     #define dws_EZERO                                                      0     /* no error */
  30.  
  31.     /* The following 3 errors may be triggered by any dws_ function */
  32.     #define dws_NOTINITTED                                             1
  33.     #define dws_ALREADYINITTED                                     2
  34.     #define dws_NOTSUPPORTED                                         3
  35.  
  36.     /* The following 4 errors may be triggered by dws_DetectHardWare */
  37.     #define dws_DetectHardware_UNSTABLESYSTEM      4
  38.     #define dws_DetectHardware_BADBASEPORT             5
  39.     #define dws_DetectHardware_BADDMA                      6
  40.     #define dws_DetectHardware_BADIRQ                      7
  41.  
  42.     /* The following error may be triggered by dws_Kill */
  43.     #define dws_Kill_CANTUNHOOKISR                             8
  44.  
  45.     /* The following error may be triggered by any dws_X (mixer) function */
  46.     #define dws_X_BADINPUT                                             9
  47.  
  48.     /* The following 3 errors may be triggered by any dws_D (dig) function */
  49.     #define dws_D_NOTADWD                                              10
  50.     #define dws_D_NOTSUPPORTEDVER                              11
  51.     #define dws_D_INTERNALERROR                                  12
  52.  
  53.     /* The following error may be triggered by dws_DPlay */
  54.     #define dws_DPlay_NOSPACEFORSOUND                      13
  55.  
  56.     /* The following 2 errors may be triggered by dws_DSetRate */
  57.     #define dws_DSetRate_FREQTOLOW                             14
  58.     #define dws_DSetRate_FREQTOHIGH                          15
  59.  
  60.     /* The following 3 errors may be triggered by dws_MPlay */
  61.     #define dws_MPlay_NOTADWM                                      16
  62.     #define dws_MPlay_NOTSUPPORTEDVER                      17
  63.     #define dws_MPlay_INTERNALERROR                          18
  64.  
  65.     /*
  66.      . The following error may be triggered by any dws_ function
  67.      . (except dws_ErrNo and dws_Init) if called from an Interrupt
  68.      . Service Routine (ISR).  If you're not sure whether this applies
  69.      . to you: it probably doesn't.
  70.     */
  71.     #define dws_BUSY                                                         19
  72.  
  73.     /*
  74.      . The following error may be triggered by dws_Init, dws_Kill,
  75.      . and dws_DetectHardware.    It will only occur if interrupts are
  76.      . disabled.    Interrupts must be enabled when calling.    If you're
  77.      . not sure whether this applies to you: it probably doesn't.
  78.     */
  79.     #define dws_IRQDISABLED                                          20
  80.  
  81.  
  82. /*---------------------------------------------------------------------------*/
  83.  
  84.  
  85.     /*
  86.      . The follwing section defines bitfields which are used by various
  87.      . dws_ functions.    Each bit in a bitfield, by definition, may be
  88.      . set/reset independantly of all other bits.
  89.     */
  90.  
  91.     /* The following 2 consts indicate the capabilities of the user's hardware */
  92.     #define dws_capability_FM                                      0x0001
  93.     #define dws_capability_DIG                                     0x0002
  94.  
  95.     /* The following 2 consts indicate the status of specified digital sounds */
  96.     #define dws_DSOUNDSTATUSPLAYING                          0x0001
  97.     #define dws_DSOUNDSTATUSSEQUENCED                      0x0002
  98.  
  99.     /* The following 2 consts indicate the status of music playback */
  100.     #define dws_MSONGSTATUSPLAYING                             0x0001
  101.     #define dws_MSONGSTATUSPAUSED                              0x0002
  102. /*****************************************************************************/
  103.  
  104.  
  105.  
  106.     /*
  107.      . The following 3 types are used by the STK
  108.      .
  109.      . If you are already typedefing these names, simply put the line
  110.      .     #define stddef_INCLUDE
  111.      . before the line
  112.      .     #include <dws.h>
  113.      . in every source file which references the STK.
  114.     */
  115.     #ifndef stddef_INCLUDE
  116.         typedef unsigned char byte;
  117.         typedef unsigned int    word;
  118.         typedef unsigned long dword;
  119.     #endif
  120. /*****************************************************************************/
  121.  
  122.  
  123.  
  124.     /*
  125.      . The following section typedefs the structs used by the STK.    In each
  126.      . case, the user must create an instance of the struct prior to making
  127.      . a call to an STK function which takes a pointer to it.  The STK does
  128.      . not keep a pointer to any of these structs internally; after the call
  129.      . returns, you may deallocate it, if you wish.
  130.      .
  131.      . NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  132.     */
  133.  
  134.  
  135.     /*
  136.      . dws_DetectHardWare can be told _not_ to autodetect particular values
  137.      . about the installed hardware.    This is useful if detecting DMA channel,
  138.      . for example, consistently causes a machine lockup.  To override the
  139.      . autodetect for a setting, set the corresponding field in this struct
  140.      . to the correct value.    Otherwise, set the field to ffff hex.  Since
  141.      . the autodetect is reliable, this is the recommended course of action,
  142.      . except in cases of known problems.
  143.     */
  144.     typedef struct
  145.     {
  146.         word baseport;            /* base address of sound card (often 220 hex) */
  147.  
  148.         word digdma;                /* DMA channel */
  149.         word digirq;                /* IRQ level */
  150.  
  151.         byte reserved[10];
  152.  
  153.     } dws_DETECTOVERRIDES;
  154.  
  155.  
  156.     /*
  157.      . A pointer to this struct is passed to dws_DetectHardWare, which fills
  158.      . it in.  It is then passed unmodified to dws_Init.    If you plan on
  159.      . writing this struct out to a file, it's important that you write
  160.      . the entire contents.  There is information (for internal STK use only)
  161.      . in the reserved[] field!
  162.     */
  163.     typedef struct
  164.     {
  165.         word baseport;            /* base address of sound card (often 220 hex) */
  166.         word capability;        /* see #defines, above */
  167.  
  168.         /* The following 3 fields are only valid if FM music is supported */
  169.         word mustyp;                /* 0=none, 1=OPL2 */
  170.         word musnchan;            /* 1=mono */
  171.         word musnvoice;         /* number of voices supported by hardware(11 for FM) */
  172.  
  173.         /* The following 2 fields are only valid if digitized sound is supported */
  174.         word dignbits;            /* 0=none, 8=8 bit */
  175.         word dignchan;            /* 1=mono */
  176.  
  177.         word digdma;                /* DMA channel */
  178.         word digirq;                /* IRQ level */
  179.  
  180.         word mixtyp;                /* 1=software, 2+ is hardware */
  181.  
  182.         byte reserved[44];    /* there are important values in here... */
  183.  
  184.     } dws_DETECTRESULTS;
  185.  
  186.  
  187.     /*
  188.      . A pointer to this struct is passed as a parameter to dws_Init.  This
  189.      . allows the user to tell the STK to use less than the full capabilities
  190.      . of the installed sound hardware, and/or the user's sound board
  191.      . may not support every feature of the STK.
  192.     */
  193.     typedef struct
  194.     {
  195.         word musictyp;                /* 0=No Music, 1=OPL2 */
  196.  
  197.         word digtyp;                    /* 0=No Dig, 8=8bit */
  198.         word digrate;                 /* sampling rate, in Hz */
  199.         word dignvoices;            /* number of voices (up to 16) */
  200.         word dignchan;                /* 1=mono */
  201.  
  202.         byte reserved[6];
  203.  
  204.     } dws_IDEAL;
  205.  
  206.  
  207.     /*
  208.      . A pointer to this struct is passed to dws_DPlay.
  209.      . Note that the soundnum field is filled in by dws_DPlay as a return value.
  210.     */
  211.     typedef struct
  212.     {
  213.         byte _far *snd;             /* pointer to buffer which holds a .DWD file */
  214.         word count;                     /* number of times to play, or 0=infinite loop */
  215.         word priority;                /* higher numbers mean higher priority */
  216.         word presnd;                    /* soundnum to sequence sound _after_ */
  217.         word soundnum;                /* dws_DPlay returns a snd number from 10-65535 */
  218.  
  219.         byte reserved[20];
  220.  
  221.     } dws_DPLAY;
  222.  
  223.  
  224.     /* A pointer to this struct is passed to dws_MPlay. */
  225.     typedef struct
  226.     {
  227.         byte _far *track;         /* pointer to buffer which holds a .DWM file */
  228.         word count;                     /* number of times to play, or 0=infinite loop */
  229.  
  230.         byte reserved[10];
  231.  
  232.     } dws_MPLAY;
  233. /*****************************************************************************/
  234.  
  235.  
  236.  
  237.     #ifdef __cplusplus
  238.         extern "C" {
  239.     #endif
  240. /*****************************************************************************/
  241.  
  242.  
  243.     /*
  244.      . This function is callable at any time.  It returns the number of the
  245.      . last error which occured.
  246.     */
  247.     word    _far _pascal dws_ErrNo(void);
  248. /*---------------------------------------------------------------------------*/
  249.  
  250.  
  251.     /*
  252.      . This function is called at the end of the timer ISR (interrupt service
  253.      . routine).    If you're using the optional DWT (DW Timer), this happens
  254.      . automagically.  If you wrote your own timer handler routine, you must
  255.      . call this function regularly.
  256.     */
  257.     void    _far _pascal _loadds _saveregs dws_Update(void);
  258. /*---------------------------------------------------------------------------*/
  259.  
  260.  
  261.     /*
  262.      . Each function in this section has a boolean return value.    A 0 (false)
  263.      . indicates that the function failed in some way.    In this case, call
  264.      . dws_ErrNo to get the specific error.  Otherwise, a return value of 1
  265.      . (true) indicates that all is well.
  266.     */
  267.     word    _far _pascal dws_DetectHardWare(dws_DETECTOVERRIDES _far *dov,
  268.                                                                                 dws_DETECTRESULTS _far *dr);
  269.  
  270.     word    _far _pascal dws_Init(dws_DETECTRESULTS _far *dr,
  271.                                                             dws_IDEAL _far *ideal);
  272.  
  273.     /*
  274.      . If the program has called dws_Init, it _MUST_ call dws_Kill before it
  275.      . terminates.
  276.      .
  277.      . NB: Trap critical errors.    Don't let DOS put up the
  278.      .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  279.     */
  280.     word    _far _pascal dws_Kill(void);
  281.  
  282.  
  283.     /*
  284.      . The following 3 functions comprise the mixer section of the STK.  A
  285.      . value of 0 turns a channel off; a value of 255 is the loudest.
  286.     */
  287.     word    _far _pascal dws_XMaster(word volume);
  288.  
  289.     word    _far _pascal dws_XMusic(word volume);
  290.  
  291.     word    _far _pascal dws_XDig(word volume);
  292.  
  293.  
  294.     /*
  295.      . The following 10 functions comprise the digitized sound functions of
  296.      . the STK.  See the documentation for complete details.
  297.     */
  298.     word    _far _pascal dws_DPlay(dws_DPLAY _far *dplay);
  299.  
  300.     word    _far _pascal dws_DSoundStatus(word soundnumber, word _far *result);
  301.  
  302.     word    _far _pascal dws_DSetRate(word frequency);
  303.  
  304.     word    _far _pascal dws_DGetRate(word _far *result);
  305.  
  306.     /* This function is callable at any time*/
  307.     word    _far _pascal dws_DGetRateFromDWD(byte _far *snd, word _far *result);
  308.  
  309.     word    _far _pascal dws_DDiscard(word soundnum);
  310.  
  311.     word    _far _pascal dws_DDiscardAO(byte _far *snd);
  312.  
  313.     word    _far _pascal dws_DClear(void);                        /* Affects all sounds */
  314.  
  315.     word    _far _pascal dws_DPause(void);                        /* Affects all sounds */
  316.  
  317.     word    _far _pascal dws_DUnPause(void);                    /* Affects all sounds */
  318.  
  319.  
  320.     /*
  321.      . The following 5 functions comprise the music functions of the STK.
  322.      . See the documentation for complete details.
  323.     */
  324.     word    _far _pascal dws_MPlay(dws_MPLAY _far *mplay);
  325.  
  326.     word    _far _pascal dws_MSongStatus(word _far *result);
  327.  
  328.     word    _far _pascal dws_MClear(void);                        /* Kill playing song    */
  329.  
  330.     word    _far _pascal dws_MPause(void);                        /* Pauses music playback */
  331.  
  332.     word    _far _pascal dws_MUnPause(void);                    /* UnPauses music playback */
  333. /*****************************************************************************/
  334.  
  335.  
  336.  
  337.     #ifdef __cplusplus
  338.         }
  339.     #endif
  340.  
  341.  
  342.  
  343. #endif
  344.